home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / showbox.com / READ.ME < prev    next >
Encoding:
Text File  |  1993-06-06  |  5.1 KB  |  103 lines
  1.  
  2. Documentation for the C++ class 'showbox'.
  3. Written by Chuck Baker
  4. compuserve user I.D. 70446,441.
  5. ---------------------------------
  6.  
  7. Showbox.cpp and showbox.hpp comprise a C++ class for displaying
  8. DOS-based messages to the screen.  That is, showbox is intended to be run 
  9. from DOS applications and it means that showbox does not enter or utilize
  10. any graphics mode.
  11.  
  12. Revised June 6, 1993
  13.     The latest revision does not have the problem of the earlier revision
  14. namely, that it will not crash the heap or anything else regardless of how 
  15. many times the ReDraw function is called.  I have tested it extensively and
  16. I use this class a lot and it leaves the heap balanced once the class has been 
  17. destroyed.  During my debugging process I found that I had a tendency 
  18. to allocate too little space for strings that I intended to sprintif into.
  19. This would blow up the heap so I caution you to 'new' or 'malloc' at least
  20. twice as much space for changing things like strings as you think you'll need.
  21. I added the functions 'GetStorage' and 'KillStorage' to help debug the
  22. problems I was having with crashing the heap.
  23. Memory for internal strings and screen area preservation is now 
  24. malloc'ed/new'd instead of being of fixed length.  This causes the class to
  25. take even less stack than it did before.
  26.  
  27. May I recommend that you read all of this.  The idea of showing a
  28. text-based box on the screen I admit, is not too remarkable at first glance
  29. but this class allows many boxes on the screen and they are easy to
  30. implement, auto save underlying area, store small on the stack and
  31. auto destruct/restore underlying area when they destruct.
  32.  
  33. Showbox writes directly to the screen and assumes video memory
  34. starts at segment B800h so it cannot be used on monochrome systems where
  35. video memory starts at segment B000h.
  36.  
  37. Showbox will display a shaded box with a given title, message 
  38. attributes at optional x-y coords.  If no coordinates are supplied then
  39. the first box will be based at x=10 y=5.  Subsequent boxes will be overlapped
  40. by 3 chars right and 3 chars down.   See function 'NextPos'.
  41. The box is auto-sized up to 60 characters wide, 
  42. then the message will wrap-around to the next line of the box.
  43. Text is always left justified and the newline character '\n' embedded in the
  44. message starts a new line.  Multiple newline characters create empty lines 
  45. in the box.  The underlying area where the box and it's shadow will be
  46. displayed is saved when the box is created and restored when the box 
  47. is destroyed.
  48.  
  49. As each box is created with the Box constructor, storage is allocated
  50. from the heap.  One of the Box functions "void Box :: Redraw( char * Msg )"
  51. allows refilling the box when the same box is used for many messages.
  52. The box will be resized if the later string is longer than the 
  53. former string.
  54.  
  55.     One of the things that I like about using the heap to store
  56. the underlying image, message and title is that the Box object can easily 
  57. be put on the stack, that is declared at the beginning of a function just 
  58. like any other type without having to worry about new and delete.  
  59. When the box goes out of scope for any reason it is automatically 
  60. destroyed so you can return from the function without worry about storage.
  61.  
  62. You may notice some filtering for messages beginning with the letters "SV".
  63. This is for my application's use and you can remove it without consequence.
  64.  
  65. The constructor of showbox is overloaded three ways.  I use the second
  66. constructor the most because it gives a consistent look to the program
  67. due to the autoplacement of the overlapping boxes.
  68. Remember that the box can be created at the top of a function and re-filled
  69. later in the function.
  70. Box :: Box ( char * Title, char * Msg, int ReqXpos, int ReqYpos, uchar ReqAttrib )
  71. Box :: Box ( char * Title, char * Msg, uchar ReqAttrib )
  72. Box :: Box ( char * Title, int ReqXpos, int ReqYpos, uchar ReqAttrib )
  73.  
  74. There is also a sub-class to the Box class named ErrorBox.  This is to
  75. display error messages consistently.
  76. ErrorBox :: ErrorBox( char * Msg )
  77.  : Box( "ERROR",Msg,BRIGHTWHITEFORGROUND + REDBACKGROUND )
  78.  
  79.  You'll see that this sub-class checks a global variable 'ContinuousFlag'
  80.  to decide whether to wait for a key press after displaying the error message
  81.  or just wait three seconds then continue.
  82. // flag to tell tests that they should run continuously
  83. extern unsigned ContinuousFlag;
  84.  
  85.  
  86. Keep in mind that this is really just a kernal for you to build from.
  87. I've considered breaking the class up a little more so maybe the most
  88. base class would do nothing but draw a box. Then have a sub-class to 
  89. overlay the text and one level higher yet to display error messages
  90. but who has the time??  And, it's useful the way it is.
  91.  
  92.     Check it out, understand it, good luck.
  93.  
  94.     Keep in mind that there may be some bits that left out
  95. because I removed an include file with some defines in it but
  96. I think that anything that I left out should be intuitively obvious
  97. and simple to fix when you compile and link.
  98.  
  99.     Last but not least, if you create a better version of this
  100. concept I'd enjoy getting hold of it.  Thanks.
  101.  
  102.     Chuck
  103.